package com.smart.community.feign.region.service;

import com.smart.community.feign.region.dto.AddressInfoDTO;
import com.smart.community.feign.region.dto.CommunityInfoDTO;
import com.smart.community.feign.region.fallback.RegionAddressFeignFallbackFactory;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * 区域地址Feign接口
 * 提供根据房户ID、单元ID、楼栋ID、社区ID获取详细地址的功能
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 */
@FeignClient(
    name = "smart-community-region",
    path = "/feign/region",
    fallbackFactory = RegionAddressFeignFallbackFactory.class,
    contextId = "regionAddressFeignService"
)
public interface RegionAddressFeignService {
    
    /**
     * 根据房户ID获取详细地址
     * 返回格式："{省}{市}{区县}{街道/城镇}{社区名}{楼栋号}{单元号}{房户号}"
     * 
     * @param householdId 房户ID
     * @return 详细地址信息
     */
    @GetMapping("/region/address/household/{householdId}")
    AddressInfoDTO getAddressByHouseholdId(@PathVariable("householdId") Long householdId);
    
    /**
     * 根据单元ID获取详细地址
     * 返回格式："{省}{市}{区县}{街道/城镇}{社区名}{楼栋号}{单元号}"
     * 
     * @param unitId 单元ID
     * @return 详细地址信息
     */
    @GetMapping("/region/address/unit/{unitId}")
    AddressInfoDTO getAddressByUnitId(@PathVariable("unitId") Long unitId);
    
    /**
     * 根据楼栋ID获取详细地址
     * 返回格式："{省}{市}{区县}{街道/城镇}{社区名}{楼栋号}"
     * 
     * @param buildingId 楼栋ID
     * @return 详细地址信息
     */
    @GetMapping("/region/address/building/{buildingId}")
    AddressInfoDTO getAddressByBuildingId(@PathVariable("buildingId") Long buildingId);
    
    /**
     * 根据社区ID获取详细地址
     * 返回格式："{省}{市}{区县}{街道/城镇}{社区名}"
     * 
     * @param communityId 社区ID
     * @return 详细地址信息
     */
    @GetMapping("/region/address/community/{communityId}")
    AddressInfoDTO getAddressByCommunityId(@PathVariable("communityId") Long communityId);
    
    /**
     * 批量根据房户ID获取详细地址
     * 
     * @param householdIds 房户ID列表
     * @return 详细地址信息列表
     */
    @PostMapping("/region/address/households/batch")
    List<AddressInfoDTO> getAddressesByHouseholdIds(@RequestBody List<Long> householdIds);
    
    /**
     * 批量根据单元ID获取详细地址
     * 
     * @param unitIds 单元ID列表
     * @return 详细地址信息列表
     */
    @PostMapping("/region/address/units/batch")
    List<AddressInfoDTO> getAddressesByUnitIds(@RequestBody List<Long> unitIds);
    
    /**
     * 批量根据楼栋ID获取详细地址
     * 
     * @param buildingIds 楼栋ID列表
     * @return 详细地址信息列表
     */
    @PostMapping("/region/address/buildings/batch")
    List<AddressInfoDTO> getAddressesByBuildingIds(@RequestBody List<Long> buildingIds);
    
    /**
     * 批量根据社区ID获取详细地址
     * 
     * @param communityIds 社区ID列表
     * @return 详细地址信息列表
     */
    @PostMapping("/region/address/communities/batch")
    List<AddressInfoDTO> getAddressesByCommunityIds(@RequestBody List<Long> communityIds);

    /**
     * 查询全部社区集合
     * 
     * @return 社区信息列表
     */
    @GetMapping("/region/communities/all")
    List<CommunityInfoDTO> getAllCommunities();
} 